Summary

• Add send_keys_batch — sends an ordered batch of raw key/text operations to tmux panes and returns a typed per-operation result (index, resolved pane, success, error, elapsed). on_error selects stop-at-first-failure or continue-and-report, an optional timeout aborts a long-running batch, and every operation carries its own pane/window targeting.
• Keep the batch homogeneous by design — it sends raw input only and does not compose send → wait → capture. Authored command completion stays with run_command; repeated observation stays with capture_since. This preserves clean per-operation error attribution instead of growing a workflow DSL inside one tool.
• Harden audit redaction for batched payloads — nested operations[].keys are digested to a length + SHA-256 prefix exactly like top-level send_keys, and malformed or schema-violating operation payloads are redacted by shape before the audit log can persist a raw value from an invalid request.
• Preserve recovery suggestions in batch errors — each per-operation error string now carries the suggestion hint from the underlying ToolError, so a client recovering from one failed operation gets the same guidance a single send_keys call would.
• Reframe the I/O guidance around three primitives — docs, prompt recipes, and tool docstrings now route authored shell commands through run_command, raw TUI / persistent-shell input through send_keys / send_keys_batch, and repeated observation through capture_since, with wait_for_channel reserved for custom shell completion.

Changes by area

Tool surface

• src/libtmux_mcp/tools/pane_tools/io.py: send_keys_batch runtime — ordered iteration, on_error handling, a cooperative timeout checked between operations, and suggestion-preserving error capture.
• src/libtmux_mcp/models.py: SendKeysOperation (strict, extra="forbid"), SendKeysOperationResult, and SendKeysBatchResult.
• src/libtmux_mcp/tools/pane_tools/__init__.py, server.py: register the tool at the mutating tier and refresh the server instructions.

Audit middleware

• src/libtmux_mcp/middleware.py: digest nested operations[].keys; redact malformed, non-list, and unknown-field operation payloads by shape before they can be logged.

Prompts & docs

• src/libtmux_mcp/prompts/recipes.py: rewrite run_and_wait to teach run_command instead of a manual send_keys + wait_for_channel + capture_pane sequence.
• docs/: new send-keys-batch tool page; prompts, quickstart, recipes, gotchas, and topic guides reframed around the three primitives; Sphinx cross-reference roles fixed for the new tools.
• README.md, CHANGES: workflow overview and unreleased changelog entry.

Tests

• tests/test_pane_tools.py: ordering, stop/continue, empty rejection, unknown-field rejection, timeout abort, suggestion preservation, and docstring routing.
• tests/test_middleware.py: redaction of well-formed, malformed, and nonschema batch payloads.
• tests/test_prompts.py, tests/test_server.py: updated prompt template and server-instruction expectations.

Design decisions

• Homogeneous batch, not a workflow DSL: send_keys_batch deliberately refuses heterogeneous send → wait → capture steps. Mixing operation kinds would blur per-operation error attribution and grow an ad-hoc orchestration language inside a single MCP tool; authored completion already has run_command and observation has capture_since.
• Redaction runs before schema validation: the audit middleware summarizes raw arguments before fastmcp validates them, so it cannot assume well-formed SendKeysOperation dicts. It checks each field by type and redacts anything unexpected — a bare string, a non-dict list item, or an unknown key can never leak a payload into the log.
• Cooperative timeout, not preemptive: timeout is evaluated between operations rather than interrupting an in-flight send_keys. tmux key delivery is effectively instantaneous, so the guard exists to bound a long batch and stop spending agent tokens — not to kill a single hung send.

Test plan

• Full verification chain: uv run ruff check ., uv run ruff format ., uv run mypy ., uv run py.test --reruns 0, just build-docs
• test_send_keys_batch_sends_operations_in_order — operations dispatch in submitted order with per-operation results
• test_send_keys_batch_stops_after_operation_error / test_send_keys_batch_continues_after_operation_error — on_error semantics and stopped_at
• test_send_keys_batch_rejects_empty_operations — empty batch raises an expected error
• test_send_keys_operation_rejects_unknown_fields — extra="forbid" rejects misnamed fields
• Batch timeout abort and per-operation suggestion preservation
• test_summarize_args_redacts_send_keys_batch_operations plus malformed / nonschema payload redaction
• test_send_keys_docstring_routes_authored_commands_to_run_command — docstring routes authored commands to run_command

Closes #49.
Closes #61.
Refs #50.